前一篇把需要的檢查與收尾工作處理好後，這份 change 就準備進入 archive 了。接下來，除了把 delta specs 更新回正式 specs，前面留下的規劃、實作線索與討論紀錄，也要一起整理。
這裡有幾件我在意的事：規格要完整更新，之後要找得到修改的原因與實作紀錄；如果原本的 discussion 還有其他主題沒談完，也不能因為一份 change 完成，就一起收起來。
我一開始讓 Speclink 沿用前面介紹過的 Spectra 2.3.1 archive；隨著使用經驗變多，我才開始依照自己的想法與習慣調整幾個地方。
先從更新正式 specs 時可能遇到的問題看起：如果同一份 change 裡，只有一部分規格能正常合併，archive 該怎麼處理？
【Day - 11】提過，Spectra 2.3.1 遇到找不到目標的規格修改時，仍可能更新其他規格並完成歸檔。這不是我希望的結果：只要有一份規格還不能合併，我就希望整份 change 先留下來，等問題處理好再一起更新。
【Day - 19】已經處理過 capability 名稱。不過，規格目錄找對了，裡面的 requirement 仍可能對不上。例如 AI 把全新的 requirement 寫進 MODIFIED，或另一份 change 先修改了同一條 requirement 的名稱，都可能讓這次 delta 找不到要修改的內容。
我們先用一份同時調整 auth 與 session 的 change 來看：
add-mfa
├── specs/auth/spec.md
└── specs/session/spec.md
假設 auth 的修改可以正常套用，session 要修改的 requirement 卻已經改名。如果這時只更新 auth 就完成歸檔，之後還得回頭確認哪些內容已經更新、哪些沒有。
因此，我讓 Speclink 的 CLI 在寫入前，先確認這次所有 capabilities 都能合併。只要有一項有問題，就先不更新正式 specs，也不歸檔 change，等 AI 根據錯誤訊息修正後再重試。這和【Day - 9】介紹的 OpenSpec CLI 作法很接近，都是全部確認好後才開始寫入。
版本補充： Spectra 3.0.0 也已改善找不到 requirement 時仍完成歸檔的問題，詳見【Day - 11】。
那要確認哪些事情呢？修改是否符合需求，仍然由 AI 比較與判斷；CLI 則負責檢查名稱與操作是否對得上，例如：
ADDED 要新增的 requirement，是否已經存在。MODIFIED、REMOVED 或 RENAMED 指定的 requirement，是否找得到。如果找到多個問題，CLI 會一起列出，讓 AI 一次處理，不必修完一個、重跑後才發現下一個。
除了這些檢查，新 capability 的 Purpose 也要確認。【Day - 19】提過，這段內容會在 propose 時先寫好，archive 直接沿用；如果缺少、空白或寫得太短，就先停止歸檔。至於修改既有 capability，則保留正式 spec 原本的 Purpose。
確認全部能合併後，才會建立 snapshot 並更新正式 specs：
寫入出錯時怎麼辦？ 這裡保證的是規格檢查沒通過時，不會開始更新正式 specs。全部檢查通過後，archive 會先替原本的正式 specs 建立 snapshot；若後續寫入遇到磁碟或權限錯誤，仍然需要透過 snapshot 與 Git 復原。
除了確認名稱找不找得到，還要留意 requirement 裡的情境有沒有少掉。【Day - 7】提過，MODIFIED 會整段取代原本的 requirement，所以除了這次要改的內容，原本仍然適用的 scenarios 也要一起寫進 delta。
例如，原本有三個情境，這次只需要調整其中一個。AI 如果只寫了要改的那個，漏掉另外兩個，合併後，那兩個原本不用改的情境也會從正式 spec 裡消失。
但少了一個情境，也可能是我們已經決定不再支援它。CLI 只看文件，無法知道這是刻意刪除，還是不小心漏寫。所以，我讓 Speclink 多檢查這件事：原本的 scenarios 都要保留；確定要刪除時，就在 MODIFIED 區段裡加上註記：
<!-- REMOVED-SCENARIO: 離線時保留操作 -->
這行註記是在告訴工具：「離線時保留操作」是這次確定要拿掉的情境。有了這個說明，archive 才會允許刪除；少掉的情境如果沒有註記，就會先停止合併，讓 AI 回頭確認。
寫入正式 spec 前，工具會移除這行註記，讓正式規格只留下目前適用的內容。之後想知道當時刪掉了什麼，仍然可以到 archived change 裡查看。
除了保留這次修改的內容，我也希望日後讀到正式規格時，能找到它來自哪份 change，以及實作時留下的檔案紀錄。接下來就是 @trace 與 evidence 各自負責的部分。
@trace 留下規格來源，evidence 保存實作線索【Day - 10】介紹的 Spectra @trace，除了記錄來源 change 與歸檔日期，也會留下 code、tests 清單。到了【Day - 20】，我已經把逐 task 的檔案線索放進 .evidence.json，而且這份紀錄會跟著整份 change 一起保存。因此，Speclink 的 @trace 就不再重複放檔案清單，只留下 source 與 updated：
<!-- @trace
source: add-mfa
updated: 2026-08-30
-->
新增或修改 requirement 時，archive 都會寫入這段註解，即使沒有 .evidence.json 也一樣。source 回答的是「這條 requirement 最近由哪份 change 加入或更新」，updated 則記下歸檔日期。要看當時的實作線索，再到那份 archived change 裡找 evidence：
只看註解不太容易想像 Speclink Desktop 會怎麼顯示，所以我請 Codex 準備了一組已完成 archive 的示範資料。先看正式規格：畫面不會直接攤開註解原文，而是在 requirement 下方顯示「來源變更：improve-login-feedback」：
@trace 只保留最近一次來源。下一份 change 再修改同一條 requirement 時，來源就會更新；更早的變更，仍然要回到 Git 與 archived changes 查找。
把 @trace 和 evidence 分開後，archive 還有一份資料要處理：和 change 連在一起的 discussion。如果這份 change 做完了，原本的討論卻還有其他主題沒談完，它應該跟著一起封存嗎？
【Day - 17】看過，一場 discussion 可以先把談妥的主題接進 change，剩下的內容繼續留在 Rounds。這裡的「已轉出」只代表其中一項內容已經進入後面的規劃，不表示整場 discussion 已經寫下 Conclusion。
目前 Speclink 會把 change 和 discussion 分開判斷。change 已經完成，就可以照常 archive；discussion 要不要跟著進入 archive，則會確認兩件事：
Conclusion。這兩個條件不必照固定順序完成。如果 discussion 先有 Conclusion，但還有其他 changes 正在進行，它就繼續留著，等最後一份 change archive 時再一起封存。反過來，如果最後一份 change 先完成，change 仍然會正常 archive，discussion 則留在原本的位置繼續談；等剩下的問題談完、寫下 Conclusion，而且沒有其他進行中的相關 change 後，discussion 才會自動移進 openspec/discussions/archive/。
如果 discussion 最後的結論是「不做」，沒有建立任何 change，則可以像【Day - 16】提過的作法，寫完 Conclusion 後直接封存。把這幾種順序放在一起，就會得到下面這張圖：
archive 完成後，如果只是想知道系統現在怎麼運作，直接看正式 specs 就夠了。可是，當我想追問「這條 requirement 為什麼會出現？當時比較過哪些方向？實作時碰過哪些檔案？」就不能只停在正式規格，而是要沿著 Speclink 留下的關係一層層往回找。
| 去哪裡看？ | 可以查到什麼？ |
|---|---|
| 正式 specs | 系統目前應該怎麼運作。 |
@trace |
這條 requirement 最近的來源 change 與更新日期。 |
| archived change | 當時的 proposal、delta specs、design 與 tasks。 |
.evidence.json |
每項 task 留下的執行背景與檔案線索，不是測試通過的證明。 |
| 來源 discussion | 當時比較過的方向與決定；這場討論可能仍在進行中，也可能已封存。 |
在 Speclink Desktop 的「已封存的變更」，畫面中的 improve-login-feedback 即使已經 archive，仍然可以重新打開 proposal，查看當時為什麼要改、準備調整哪些內容；其他 artifacts 也會留在相同的 archived change 裡：
如果還想知道當時討論過哪些方向，也可以回頭查看來源 discussion。像示範中的 login-flow 已經封存，仍然能從 Speclink Desktop 的「已封存的討論」打開，查看 Context 與每一輪討論：
實際回查時，可以從正式 spec 的 @trace 找到最近一份 archived change，先看當時的規劃。想找某項 task 碰過的檔案，就查看裡面的 .evidence.json；如果 change 留有 from_discussion，也能沿著它回到來源討論，了解當時為什麼做這個決定：
這樣從眼前的一條 requirement 出發，就有地方查當時的規劃與決策。更早的修改歷史，則仍然要搭配 Git 與其他 archived changes。
【Day - 21】提過，有些 changes 要等前一份完成才能開工。因此，archive 完成後，AI 會再執行一次 speclink plan --json，確認原本等待的工作現在能不能開始，再提醒我接下來可以做哪一份 change。
這裡只會提供建議，不會直接開始 apply。要不要繼續、要不要同時進行多份 changes，仍然由我決定。
除了接著做下一份 change，剛更新的正式 specs 還有另一個用途：整理成操作手冊，讓需要使用系統的人更容易閱讀。
正式 specs 很適合回答系統現在有哪些行為，卻不一定能讓 PM、SA 或剛接手的人直接拼出完整的操作順序。
如果 archive 後還需要一份能照著閱讀與操作的文件，就可以另外執行 Manual。這個 Skill 會把正式 specs 裡使用者看得到、會操作的內容重新排成操作流程，產生到 openspec/manual/。它不是照 capability 一份份複製，而是改成從哪裡開始、下一步做什麼，以及遇到問題時該怎麼處理。
從 Speclink Desktop 打開手冊時，可以先從首頁了解系統概念，再依照自己的角色選擇閱讀入口：
首頁左側也能看到部分頁面標示「可能過期」。後續 change 更新相關 spec 時，Speclink Desktop 就會提醒手冊可能需要更新；archive 不會直接改寫手冊，仍要另外執行 Manual。
進入單一頁面後，則會按照實際操作順序往下說明，並保留來源 capabilities 與前後頁導覽：
手冊的內容仍然來自 specs。如果規格寫錯或漏掉操作，產生的手冊也需要跟著修正，不能產生後就直接當成正確答案。
到這裡，這份 change 不只完成了歸檔，也留下日後可以回查的規劃與實作紀錄。更新後的正式 specs，則可以繼續拿來整理操作手冊。
寫到這裡，我才發現：從【Day - 13】正式介紹 Speclink，一路寫到這一篇，轉眼已經用了十二篇。照這個速度，Speclink 是不是 30 天根本講不完？
我只能說：不！我其實已經講完了！XD
至少，一份 change 從討論、規劃、實作與需要的檢查，到最後歸檔，我們已經一起走過一遍了。
不過，功能一項項完成，codebase 裡也可能慢慢累積重複或不好維護的程式。這時候，能不能請 AI 回頭找出值得整理的地方，再由我們決定要不要改呢？接下來，就來聊聊我怎麼處理這個問題吧！
iThome鐵人賽
看影片追技術